<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>test::basic_stream</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Beast">
<link rel="up" href="../ref.html" title="This Page Intentionally Left Blank 2/2">
<link rel="prev" href="boost__beast__basic_stream/async_write_some.html" title="basic_stream::async_write_some">
<link rel="next" href="boost__beast__test__basic_stream/executor_type.html" title="test::basic_stream::executor_type">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost__beast__basic_stream/async_write_some.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost__beast__test__basic_stream/executor_type.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="beast.ref.boost__beast__test__basic_stream"></a><a class="link" href="boost__beast__test__basic_stream.html" title="test::basic_stream">test::basic_stream</a>
</h4></div></div></div>
<p>
        A two-way socket useful for unit testing.
      </p>
<h5>
<a name="beast.ref.boost__beast__test__basic_stream.h0"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__test__basic_stream.synopsis"></a></span><a class="link" href="boost__beast__test__basic_stream.html#beast.ref.boost__beast__test__basic_stream.synopsis">Synopsis</a>
      </h5>
<p>
        Defined in header <code class="literal">&lt;<a href="../../../../../../boost/beast/_experimental/test/stream.hpp" target="_top">boost/beast/_experimental/test/stream.hpp</a>&gt;</code>
      </p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span>
    <span class="keyword">class</span> <a href="../../../../../../doc/html/boost_asio/reference/Executor1.html" target="_top"><span class="emphasis"><em>Executor</em></span></a><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">basic_stream</span>
</pre>
<h5>
<a name="beast.ref.boost__beast__test__basic_stream.h1"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__test__basic_stream.types"></a></span><a class="link" href="boost__beast__test__basic_stream.html#beast.ref.boost__beast__test__basic_stream.types">Types</a>
      </h5>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Name
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/buffer_type.html" title="test::basic_stream::buffer_type">buffer_type</a></strong></span>
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/executor_type.html" title="test::basic_stream::executor_type">executor_type</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  The type of the executor associated with the object.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream__rebind_executor.html" title="test::basic_stream::rebind_executor">rebind_executor</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Rebinds the socket type to another executor.
                </p>
              </td>
</tr>
</tbody>
</table></div>
<h5>
<a name="beast.ref.boost__beast__test__basic_stream.h2"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__test__basic_stream.member_functions"></a></span><a class="link" href="boost__beast__test__basic_stream.html#beast.ref.boost__beast__test__basic_stream.member_functions">Member
        Functions</a>
      </h5>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Name
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/append.html" title="test::basic_stream::append">append</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Appends a string to the pending input data.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/async_read_some.html" title="test::basic_stream::async_read_some">async_read_some</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Start an asynchronous read.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/async_write_some.html" title="test::basic_stream::async_write_some">async_write_some</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Start an asynchronous write.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/basic_stream.html" title="test::basic_stream::basic_stream">basic_stream</a> <span class="silver">[constructor]</span></strong></span>
                </p>
              </td>
<td>
                <p>
                  Move Constructor. <br> <span class="silver">—</span><br>
                  Construct a stream.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/buffer.html" title="test::basic_stream::buffer">buffer</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Direct input buffer access.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/clear.html" title="test::basic_stream::clear">clear</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Clear the pending input area.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/close.html" title="test::basic_stream::close">close</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Close the stream.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/close_remote.html" title="test::basic_stream::close_remote">close_remote</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Close the other end of the stream.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/connect.html" title="test::basic_stream::connect">connect</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Establish a connection.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/get_executor.html" title="test::basic_stream::get_executor">get_executor</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Return the executor associated with the object.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/nread.html" title="test::basic_stream::nread">nread</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Return the number of reads.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/nread_bytes.html" title="test::basic_stream::nread_bytes">nread_bytes</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Return the number of bytes read.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/nwrite.html" title="test::basic_stream::nwrite">nwrite</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Return the number of writes.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/nwrite_bytes.html" title="test::basic_stream::nwrite_bytes">nwrite_bytes</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Return the number of bytes written.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/operator_eq_.html" title="test::basic_stream::operator=">operator=</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Move Assignment.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/operator_eq__eq_.html" title="test::basic_stream::operator==">operator==</a></strong></span>
                </p>
              </td>
<td>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/read_size.html" title="test::basic_stream::read_size">read_size</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Set the maximum number of bytes returned by read_some.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/read_some.html" title="test::basic_stream::read_some">read_some</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Read some data from the stream.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/str.html" title="test::basic_stream::str">str</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Returns a string view representing the pending input data.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/write_size.html" title="test::basic_stream::write_size">write_size</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Set the maximum number of bytes returned by write_some.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/write_some.html" title="test::basic_stream::write_some">write_some</a></strong></span>
                </p>
              </td>
<td>
                <p>
                  Write some data to the stream.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <span class="bold"><strong><a class="link" href="boost__beast__test__basic_stream/_dtor_basic_stream.html" title="test::basic_stream::~basic_stream">~basic_stream</a> <span class="silver">[destructor]</span></strong></span>
                </p>
              </td>
<td>
                <p>
                  Destructor.
                </p>
              </td>
</tr>
</tbody>
</table></div>
<h5>
<a name="beast.ref.boost__beast__test__basic_stream.h3"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__test__basic_stream.description"></a></span><a class="link" href="boost__beast__test__basic_stream.html#beast.ref.boost__beast__test__basic_stream.description">Description</a>
      </h5>
<p>
        An instance of this class simulates a traditional socket, while also providing
        features useful for unit testing. Each endpoint maintains an independent
        buffer called the input area. Writes from one endpoint append data to the
        peer's pending input area. When an endpoint performs a read and data is present
        in the input area, the data is delivered to the blocking or asynchronous
        operation. Otherwise the operation is blocked or deferred until data is made
        available, or until the endpoints become disconnected. These streams may
        be used anywhere an algorithm accepts a reference to a synchronous or asynchronous
        read or write stream. It is possible to use a test stream in a call to <code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">read_until</span></code>,
        or in a call to <a class="link" href="boost__beast__http__async_write.html" title="http::async_write"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">beast</span><span class="special">::</span><span class="identifier">http</span><span class="special">::</span><span class="identifier">async_write</span></code></a> for example. As with
        Boost.Asio I/O objects, a <a class="link" href="boost__beast__test__stream.html" title="test::stream"><code class="computeroutput"><span class="identifier">stream</span></code></a> constructs with a reference
        to the <code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">io_context</span></code> to use for handling asynchronous
        I/O. For asynchronous operations, the stream follows the same rules as a
        traditional asio socket with respect to how completion handlers for asynchronous
        operations are performed. To facilitate testing, these streams support some
        additional features:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            The input area, represented by a <a class="link" href="boost__beast__basic_flat_buffer.html" title="basic_flat_buffer"><code class="computeroutput"><span class="identifier">beast</span><span class="special">::</span><span class="identifier">basic_flat_buffer</span></code></a>, may be directly
            accessed by the caller to inspect the contents before or after the remote
            endpoint writes data. This allows a unit test to verify that the received
            data matches.
          </li>
<li class="listitem">
            Data may be manually appended to the input area. This data will delivered
            in the next call to <a class="link" href="boost__beast__test__basic_stream/read_some.html" title="test::basic_stream::read_some"><code class="computeroutput"><span class="identifier">stream</span><span class="special">::</span><span class="identifier">read_some</span></code></a> or <a class="link" href="boost__beast__test__basic_stream/async_read_some.html" title="test::basic_stream::async_read_some"><code class="computeroutput"><span class="identifier">stream</span><span class="special">::</span><span class="identifier">async_read_some</span></code></a>. This allows
            predefined test vectors to be set up for testing read algorithms.
          </li>
<li class="listitem">
            The stream may be constructed with a fail count. The stream will eventually
            fail with a predefined error after a certain number of operations, where
            the number of operations is controlled by the test. When a test loops
            over a range of operation counts, it is possible to exercise every possible
            point of failure in the algorithm being tested. When used correctly the
            technique allows the tests to reach a high percentage of code coverage.
          </li>
</ul></div>
<h5>
<a name="beast.ref.boost__beast__test__basic_stream.h4"></a>
        <span class="phrase"><a name="beast.ref.boost__beast__test__basic_stream.thread_safety"></a></span><a class="link" href="boost__beast__test__basic_stream.html#beast.ref.boost__beast__test__basic_stream.thread_safety">Thread
        Safety</a>
      </h5>
<p>
        <span class="emphasis"><em>Distinct</em></span><span class="emphasis"><em>objects:</em></span>Safe.
      </p>
<p>
        <span class="emphasis"><em>Shared</em></span><span class="emphasis"><em>objects:</em></span>Unsafe. The application
        must also ensure that all asynchronous operations are performed within the
        same implicit or explicit strand.
      </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie
      Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="boost__beast__basic_stream/async_write_some.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost__beast__test__basic_stream/executor_type.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
